<?php
/**
 * Hush Framework
 *
 * @category   Hush
 * @package	Hush_Db
 * @author	 James.Huang <shagoo@gmail.com>
 * @license	http://www.apache.org/licenses/LICENSE-2.0
 * @version	$Id: james $
 */

/**
 * @see Zend_Db
 */
require_once 'Hush/Db.php';

/**
 * @see Hush_Db_Adapter_Exception
 */
require_once 'Hush/Db/Adapter/Exception.php';

/**
 * @package Hush_Db
 */
abstract class Hush_Db_Adapter_Simple_Abstract 
{
	/**
	 * User-provided configuration
	 *
	 * @var array
	 */
	protected $_config = array();

	/**
	 * Fetch mode
	 *
	 * @var integer
	 */
	protected $_fetchMode = Hush_Db::FETCH_ASSOC;

	/**
	 * Database connection
	 *
	 * @var object|resource|null
	 */
	protected $_connection = null;

	/**
	 * Specifies whether the adapter automatically quotes identifiers.
	 * If true, most SQL generated by Zend_Db classes applies
	 * identifier quoting automatically.
	 * If false, developer must quote identifiers themselves
	 * by calling quoteIdentifier().
	 *
	 * @var bool
	 */
	protected $_autoQuoteIdentifiers = true;

	/**
	 * Constructor.
	 *
	 * $config is an array of key/value pairs or an instance of Zend_Config
	 * containing configuration options.  These options are common to most adapters:
	 *
	 * dbname		 => (string) The name of the database to user
	 * username	   => (string) Connect to the database as this username.
	 * password	   => (string) Password associated with the username.
	 * host		   => (string) What host to connect to, defaults to localhost
	 *
	 * Some options are used on a case-by-case basis by adapters:
	 *
	 * port		   => (string) The port of the database
	 * persistent	 => (boolean) Whether to use a persistent connection or not, defaults to false
	 * protocol	   => (string) The network protocol, defaults to TCPIP
	 * caseFolding	=> (int) style of case-alteration used for identifiers
	 *
	 * @param  array $config An array having configuration data
	 */
	public function __construct($config)
	{
		if (!is_array($config)) {
			throw new Hush_Db_Adapter_Exception('Adapter parameters must be in an array');
		}
		
		$this->_checkRequiredOptions($config);
		
		$options = array();
		if (array_key_exists('options', $config)) {
			// can't use array_merge() because keys might be integers
			foreach ((array) $config['options'] as $key => $value) {
				$options[$key] = $value;
			}
		}
		
		$driverOptions = array();
		if (array_key_exists('driver_options', $config)) {
			if (!empty($config['driver_options'])) {
				// can't use array_merge() because keys might be integers
				foreach ((array) $config['driver_options'] as $key => $value) {
					$driverOptions[$key] = $value;
				}
			}
		}
		
		if (!isset($config['charset'])) {
			$config['charset'] = null;
		}
		
		if (!isset($config['persistent'])) {
			$config['persistent'] = false;
		}
		
		$this->_config = array_merge($this->_config, $config);
		$this->_config['options'] = $options;
		$this->_config['driver_options'] = $driverOptions;
	}

	/**
	 * Check invalid method
	 * Throw exception if method does not exists
	 * 
	 * @param  string $name Method name
	 * @param  array $arguments Method parameters array
	 */
	public function __call ($name, $arguments)
	{
		if (!method_exists($this, $name)) {
			throw new Hush_Db_Adapter_Exception(__CLASS__ . " does not have method '$name'");
		}
	}

	/**
	 * Check for config options that are mandatory.
	 * Throw exceptions if any are missing.
	 *
	 * @param array $config
	 */
	protected function _checkRequiredOptions(array $config)
	{
		if (! array_key_exists('dbname', $config)) {
			throw new Hush_Db_Adapter_Exception("Configuration array must have a key for 'dbname' that names the database instance");
		}
		
		if (! array_key_exists('password', $config)) {
			throw new Hush_Db_Adapter_Exception("Configuration array must have a key for 'password' for login credentials");
		}
		
		if (! array_key_exists('username', $config)) {
			throw new Hush_Db_Adapter_Exception("Configuration array must have a key for 'username' for login credentials");
		}
	}

	/**
	 * Returns the underlying database connection object or resource.
	 * If not presently connected, this initiates the connection.
	 *
	 * @return object|resource|null
	 */
	public function getConnection() 
	{
		$this->_connect(); // implement in adapter classes
		return $this->_connection;
	}

	/**
	 * Prepares and executes an SQL statement with bound data.
	 *
	 * @param  mixed  $sql  The SQL statement with placeholders.
	 * @param  mixed  $bind An array of data to bind to the placeholders.
	 * @return boolean
	 */
	public function query($sql, $bind = array())
	{
		// connect to the database if needed
		$this->_connect();
		
		// make sure $bind to an array;
		// because $bind may be an object
		if (!is_array($bind)) {
			$bind = array($bind);
		}
		
		// prepare and execute the statement with profiling
		if ($this->prepare($sql)) {
			return $this->execute($bind);
		}
		
		return false;
	}

	/**
	 * Inserts a table row with specified data.
	 *
	 * @param mixed $table The table to insert data into.
	 * @param array $bind Column-value pairs.
	 * @return int  The number of affected rows.
	 */
	public function insert($table, array $bind)
	{
		// extract and quote col names from the array keys
		$cols = array();
		$vals = array();
		foreach ($bind as $col => $val) {
			$cols[] = $this->quoteIdentifier($col, true);
			$vals[] = '?';
		}

		// build the statement
		$sql = 'INSERT INTO '
			 . $this->quoteIdentifier($table, true)
			 . ' (' . implode(', ', $cols) . ') '
			 . 'VALUES (' . implode(', ', $vals) . ')';

		// execute the statement and return the number of affected rows
		if ($this->query($sql, array_values($bind))) {
			$result = $this->rowCount();
			return $result;
		}
		
		return false;
	}

	/**
	 * Updates table rows with specified data based on a WHERE clause.
	 *
	 * @param  mixed $table The table to update.
	 * @param  array $bind  Column-value pairs.
	 * @param  mixed $where UPDATE WHERE clause(s).
	 * @return int   The number of affected rows.
	 */
	public function update($table, array $bind, $where = '')
	{
		/**
		 * Build "col = ?" pairs for the statement,
		 * except for Zend_Db_Expr which is treated literally.
		 */
		$set = array();
		$i = 0;
		foreach ($bind as $col => $val) {
			$val = '?';
			$set[] = $this->quoteIdentifier($col, true) . ' = ' . $val;
		}

		$where = $this->_whereExpr($where);
		
		// Build the UPDATE statement
		$sql = 'UPDATE '
			 . $this->quoteIdentifier($table, true)
			 . ' SET ' . implode(', ', $set)
			 . (($where) ? " WHERE $where" : '');
		
		// Execute the statement and return the number of affected rows
		if ($this->query($sql, array_values($bind))) {
			$result = $this->rowCount();
			return $result;
		}
		
		return false;
	}

	/**
	 * Deletes table rows based on a WHERE clause.
	 *
	 * @param  mixed $table The table to update.
	 * @param  mixed $where DELETE WHERE clause(s).
	 * @return int   The number of affected rows.
	 */
	public function delete($table, $where = '')
	{
		$where = $this->_whereExpr($where);

		// Build the DELETE statement
		$sql = 'DELETE FROM '
			 . $this->quoteIdentifier($table, true)
			 . (($where) ? " WHERE $where" : '');

		// Execute the statement and return the number of affected rows
		if ($this->query($sql)) {
			$result = $this->rowCount();
			return $result;
		}
		
		return false;
	}
	
	/**
	 * Replace table rows with specified data based on a WHERE clause.
	 *
	 * @param  mixed $table The table to update.
	 * @param  array $bind  Column-value pairs.
	 * @return int   The number of affected rows.
	 */
	public function replace($table, array $bind)
	{
		/**
		 * Build "col = ?" pairs for the statement,
		 * except for Zend_Db_Expr which is treated literally.
		 */
		$set = array();
		$i = 0;
		foreach ($bind as $col => $val) {
			$val = '?';
			$set[] = $this->quoteIdentifier($col, true) . ' = ' . $val;
		}
		
		// Build the UPDATE statement
		$sql = 'REPLACE INTO '
			 . $this->quoteIdentifier($table, true)
			 . ' SET ' . implode(', ', $set);
		
		// Execute the statement and return the number of affected rows
		if ($this->query($sql, array_values($bind))) {
			$result = $this->rowCount();
			return $result;
		}
		
		return false;
	}
	
	/**
	 * Convert an array, string, or Zend_Db_Expr object
	 * into a string to put in a WHERE clause.
	 *
	 * @param mixed $where
	 * @return string
	 */
	protected function _whereExpr($where)
	{
		if (empty($where)) {
			return $where;
		}
		if (!is_array($where)) {
			$where = array($where);
		}
		foreach ($where as $cond => &$term) {
			// is $cond an int? (i.e. Not a condition)
			if (is_int($cond)) {
				$term = (string) $term;
			} else {
				// $cond is the condition with placeholder,
				// and $term is quoted into the condition
				$term = $this->quoteInto($cond, $term);
			}
			$term = '(' . $term . ')';
		}

		$where = implode(' AND ', $where);
		return $where;
	}

	/**
	 * Fetches all SQL result rows as a sequential array.
	 * Uses the current fetchMode for the adapter.
	 *
	 * @param string $sql  An SQL SELECT statement.
	 * @param mixed  $bind Data to bind into SELECT placeholders.
	 * @param mixed  $fetchMode Override current fetch mode.
	 * @return array
	 */
	public function fetchAll($sql, $bind = array(), $fetchMode = null)
	{
		if ($fetchMode === null) {
			$fetchMode = $this->_fetchMode;
		}
		if ($this->query($sql, $bind)) {
			return $this->_fetchAll($fetchMode);
		}
		return false;
	}

	/**
	 * Fetches the first row of the SQL result.
	 * Uses the current fetchMode for the adapter.
	 *
	 * @param string $sql An SQL SELECT statement.
	 * @param mixed  $bind Data to bind into SELECT placeholders.
	 * @param mixed  $fetchMode Override current fetch mode.
	 * @return array
	 */
	public function fetchRow($sql, $bind = array(), $fetchMode = null)
	{
		if ($fetchMode === null) {
			$fetchMode = $this->_fetchMode;
		}
		if ($this->query($sql, $bind)) {
			return $this->_fetch($fetchMode);
		}
		return false;
	}

	/**
	 * Fetches the first column of the first row of the SQL result.
	 *
	 * @param string $sql An SQL SELECT statement.
	 * @param mixed  $bind Data to bind into SELECT placeholders.
	 * @return string
	 */
	public function fetchOne($sql, $bind = array())
	{
		if ($this->query($sql, $bind)) {
			return $this->_fetchColumn(0);
		}
		return false;
	}

	public function rowCount()
	{
		return $this->_rowCount();
	}

	/**
	 * Quote a raw string.
	 *
	 * @param string $value	 Raw string
	 * @return string		   Quoted string
	 */
	protected function _quote($value)
	{
		if (is_int($value)) {
			return $value;
		} elseif (is_float($value)) {
			return sprintf('%F', $value);
		}
		return "'" . addcslashes($value, "\000\n\r\\'\"\032") . "'";
	}

	/**
	 * Safely quotes a value for an SQL statement.
	 *
	 * If an array is passed as the value, the array values are quoted
	 * and then returned as a comma-separated string.
	 *
	 * @param mixed $value The value to quote.
	 * @param mixed $type  OPTIONAL the SQL datatype name, or constant, or null.
	 * @return mixed An SQL-safe quoted value (or string of separated values).
	 */
	public function quote($value, $type = null)
	{
		$this->_connect();
		
		if (is_array($value)) {
			foreach ($value as &$val) {
				$val = $this->quote($val, $type);
			}
			return implode(', ', $value);
		}
		
		return $this->_quote($value);
	}

	/**
	 * Quotes a value and places into a piece of text at a placeholder.
	 *
	 * The placeholder is a question-mark; all placeholders will be replaced
	 * with the quoted value.   For example:
	 *
	 * <code>
	 * $text = "WHERE date < ?";
	 * $date = "2005-01-02";
	 * $safe = $sql->quoteInto($text, $date);
	 * // $safe = "WHERE date < '2005-01-02'"
	 * </code>
	 *
	 * @param string  $text  The text with a placeholder.
	 * @param mixed   $value The value to quote.
	 * @param string  $type  OPTIONAL SQL datatype
	 * @param integer $count OPTIONAL count of placeholders to replace
	 * @return string An SQL-safe quoted value placed into the original text.
	 */
	public function quoteInto($text, $value, $type = null, $count = null)
	{
		if ($count === null) {
			return str_replace('?', $this->quote($value, $type), $text);
		} else {
			while ($count > 0) {
				if (strpos($text, '?') !== false) {
					$text = substr_replace($text, $this->quote($value, $type), strpos($text, '?'), 1);
				}
				--$count;
			}
			return $text;
		}
	}

	/**
	 * Quotes an identifier.
	 *
	 * Accepts a string representing a qualified indentifier. For Example:
	 * <code>
	 * $adapter->quoteIdentifier('myschema.mytable')
	 * </code>
	 * Returns: "myschema"."mytable"
	 *
	 * Or, an array of one or more identifiers that may form a qualified identifier:
	 * <code>
	 * $adapter->quoteIdentifier(array('myschema','my.table'))
	 * </code>
	 * Returns: "myschema"."my.table"
	 *
	 * The actual quote character surrounding the identifiers may vary depending on
	 * the adapter.
	 *
	 * @param string|array $ident The identifier.
	 * @param boolean $auto If true, heed the AUTO_QUOTE_IDENTIFIERS config option.
	 * @return string The quoted identifier.
	 */
	public function quoteIdentifier($ident, $auto = false)
	{
		return $this->_quoteIdentifierAs($ident, null, $auto);
	}

	/**
	 * Quote a column identifier and alias.
	 *
	 * @param string|array $ident The identifier or expression.
	 * @param string $alias An alias for the column.
	 * @param boolean $auto If true, heed the AUTO_QUOTE_IDENTIFIERS config option.
	 * @return string The quoted identifier and alias.
	 */
	public function quoteColumnAs($ident, $alias, $auto = false)
	{
		return $this->_quoteIdentifierAs($ident, $alias, $auto);
	}

	/**
	 * Quote a table identifier and alias.
	 *
	 * @param string|array $ident The identifier or expression.
	 * @param string $alias An alias for the table.
	 * @param boolean $auto If true, heed the AUTO_QUOTE_IDENTIFIERS config option.
	 * @return string The quoted identifier and alias.
	 */
	public function quoteTableAs($ident, $alias = null, $auto = false)
	{
		return $this->_quoteIdentifierAs($ident, $alias, $auto);
	}

	/**
	 * Quote an identifier and an optional alias.
	 *
	 * @param string|array $ident The identifier or expression.
	 * @param string $alias An optional alias.
	 * @param boolean $auto If true, heed the AUTO_QUOTE_IDENTIFIERS config option.
	 * @param string $as The string to add between the identifier/expression and the alias.
	 * @return string The quoted identifier and alias.
	 */
	protected function _quoteIdentifierAs($ident, $alias = null, $auto = false, $as = ' AS ')
	{
		if (is_string($ident)) {
			$ident = explode('.', $ident);
		}
		if (is_array($ident)) {
			$segments = array();
			foreach ($ident as $segment) {
				$segments[] = $this->_quoteIdentifier($segment, $auto);
			}
			if ($alias !== null && end($ident) == $alias) {
				$alias = null;
			}
			$quoted = implode('.', $segments);
		} else {
			$quoted = $this->_quoteIdentifier($ident, $auto);
		}
		if ($alias !== null) {
			$quoted .= $as . $this->_quoteIdentifier($alias, $auto);
		}
		return $quoted;
	}

	/**
	 * Quote an identifier.
	 *
	 * @param  string $value The identifier or expression.
	 * @param boolean $auto If true, heed the AUTO_QUOTE_IDENTIFIERS config option.
	 * @return string		The quoted identifier and alias.
	 */
	protected function _quoteIdentifier($value, $auto = false)
	{
		if ($auto === false || $this->_autoQuoteIdentifiers === true) {
			$q = $this->getQuoteIdentifierSymbol();
			return ($q . str_replace("$q", "$q$q", $value) . $q);
		}
		return $value;
	}

	/**
	 * Returns the symbol the adapter uses for delimited identifiers.
	 *
	 * @return string
	 */
	public function getQuoteIdentifierSymbol()
	{
		return '"';
	}

	/**
	 * Creates a connection to the database.
	 *
	 * @return void
	 */
	abstract protected function _connect();

	/**
	 * Test if a connection is active
	 *
	 * @return boolean
	 */
	abstract public function isConnected();

	/**
	 * Force the connection to close.
	 *
	 * @return void
	 */
	abstract public function closeConnection();

	/**
	 * Prepare a statement and return a PDOStatement-like object.
	 *
	 * @param string $sql SQL query
	 * @return PDOStatement
	 */
	abstract public function prepare($sql);

	/**
	 * Executes a prepared statement.
	 *
	 * @param array $params OPTIONAL Values to bind to parameter placeholders.
	 * @return bool
	 */
	abstract public function execute(array $params = null);

	/**
	 * Fetches a row from the result set.
	 *
	 * @param int $style  OPTIONAL Fetch mode for this fetch operation.
	 * @param int $cursor OPTIONAL Absolute, relative, or other.
	 * @param int $offset OPTIONAL Number for absolute or relative cursors.
	 * @return mixed Array, object, or scalar depending on fetch mode.
	 * @throws Zend_Db_Statement_Mysqli_Exception
	 */
	abstract protected function _fetch($style = null, $cursor = null, $offset = null);

	/**
	 * Returns an array containing all of the result set rows.
	 *
	 * @param int $style OPTIONAL Fetch mode.
	 * @param int $col   OPTIONAL Column number, if fetch mode is by column.
	 * @return array Collection of rows, each in a format by the fetch mode.
	 */
	abstract protected function _fetchAll($style = null, $col = null);

	/**
	 * Returns a single column from the next row of a result set.
	 *
	 * @param int $col OPTIONAL Position of the column to fetch.
	 * @return string One value from the next row of result set, or false.
	 */
	abstract protected function _fetchColumn($col = 0);

	/**
	 * Returns the number of rows affected by the execution of the
	 * last INSERT, DELETE, or UPDATE statement executed by this
	 * statement object.
	 *
	 * @return int	 The number of rows affected.
	 */
	abstract protected function _rowCount();

	/**
	 * Gets the last ID generated automatically by an IDENTITY/AUTOINCREMENT column.
	 *
	 * As a convention, on RDBMS brands that support sequences
	 * (e.g. Oracle, PostgreSQL, DB2), this method forms the name of a sequence
	 * from the arguments and returns the last id generated by that sequence.
	 * On RDBMS brands that support IDENTITY/AUTOINCREMENT columns, this method
	 * returns the last value generated for such a column, and the table name
	 * argument is disregarded.
	 *
	 * @param string $tableName   OPTIONAL Name of table.
	 * @param string $primaryKey  OPTIONAL Name of primary key column.
	 * @return string
	 */
	abstract public function lastInsertId($tableName = null, $primaryKey = null);

	/**
	 * Begin a transaction.
	 */
	abstract public function beginTransaction();

	/**
	 * Commit a transaction.
	 */
	abstract public function commit();

	/**
	 * Roll-back a transaction.
	 */
	abstract public function rollBack();

	/**
	 * Set the fetch mode.
	 *
	 * @param integer $mode
	 * @return void
	 */
	abstract public function setFetchMode($mode);
}